home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / asmutil / alib10.zip / ALIB3.DOC < prev    next >
Text File  |  1994-04-08  |  101KB  |  2,394 lines
  1. This document contains a list of all ALIB functions arranged alphabetically
  2. by category as follows:
  3.  
  4.  CATEGORY     LIBRARY FUNCTIONS IN THIS CATEGORY
  5.  --------     -------------------------------------------------------------
  6.  compress     SHRINK              EXPAND
  7.  
  8.  config       GET_SETUP           CHANGE_SETUP
  9.               WRITE_SETUP         SET_LIB_COLORS
  10.  
  11.  convert      BYTE_TO_DEC_STR     BYTE_TO_DEC_CRT     DEC_STR_TO_DWORD
  12.               DEC_STRZ_TO_DWORD   DEC_STRZ_TO_DWORD   DEC_STR_TO_WORD
  13.               DWORD_TO_DEC_STRX   DWORD_TO_DEC_CRTX   DWORD_TO_HEX_STR
  14.               DWORD_TO_HEX_CRT    HEX_ST_TO_BYTE      HEX_STR_TO_WORD
  15.               WORD_TO_DEC_CRT     WORD_TO_DEC_STR     WORD_TO_HEX_CRT
  16.               WORD_TO_HEX_STR     
  17.               
  18.  database     DBASE_INIT          DBASE_READ
  19.               DBASE_READ_NEXT     DBASE_READ_PREV     DBASE_APPEND
  20.               DBASE_INSERT        DBASE_REPLACE       DBASE_REMOVE
  21.               DBASE_CLOSE         DBASE_KILL
  22.               
  23.  disk         FILE_COPY           FILE_SIZE1          FILE_COUNT
  24.               FILE_FLUSH          FILE_EXIST          EXPAND_FILENAME
  25.               DECODE_FILENAME     FIND_HOME_PATH      GET_PATH
  26.               CHANGE_PATH         RESTORE_PATH        FILE_SIZE2
  27.               
  28.  display      PUT_CRT_CHR         GET_CRT_CHR         REPEAT_PUT_CRT
  29.               PUT_CRT_BLK         VERTICAL_REPEAT_CHR TABULAR_DRAW
  30.               CLEAR_SCREEN        DISPLAY_STRING      DISPLAY_STRING_FILL
  31.               DISPLAY_STRING_LIST CLEAR_WINDOW        DRAW_BOX
  32.               WINDOW_STRING       BOX_RIGHT           BOX_LEFT
  33.               BOX_UP              BOX_DOWN            BOX_EXPAND
  34.               BOX_SHRINK          GET_ANSI_COLOR      CURSOR_
  35.               SHOW_CURSOR         HIDE_CURSOR         BLINK_ON
  36.               BLINK_OFF           SAVE_WINDOW         RESTORE_WINDOW
  37.               DISK_TO_CRT         CRT_TO_DISK
  38.               
  39.  error        LIB_ERROR_HANDLER   ERROR_HANDLER       ERROR_NUMBER
  40.               ERROR_PRIME         ERROR_TABLE_HANDLER ERROR_FILE_HANDLER
  41.               SOUND_ON            SOUND_OFF           ONE_BEEP
  42.               BEEP
  43.               
  44.  float        FLOAT_OPEN          FLOAT_CLOSE         BINARY_IN
  45.               BINARY_OUT          FMOVE               F_SUBTRACT
  46.               F_ADDITION          FCOMP               F_MULTIPLY
  47.               F_DIVIDE            ROUND               TEXT_OUT
  48.               TEXT_IN             FLOAT_SET
  49.  
  50.  memory       MEM_OPEN            MEM_ALLOCATE        MEM_PUT 
  51.               MEM_GET             MEM_RELEASE         MEM_CLOSE
  52.               DOS_MEM_ALLOCATE    DOS_MEM_RELEASE     CHECK_FOR_EMS
  53.               
  54.  menu         MENU_SYSTEM         QMENU_SYSTEM
  55.               
  56.  message      MESSAGE             RANDOM              GET_RANDOM
  57.               QMESSAGE            QWARN
  58.               
  59.  mouse/key    IS_ALPHA            IS_DIGIT            IS_LOWER
  60.               IS_UPPER            TO_UPPER            TO_LOWER
  61.               CAPS_ON             NUMLOCK_ON          SCROLL_ON 
  62.               INSERT_OFF          CAPS_OFF            NUMLOCK_OFF
  63.               SCROLL_OFF          YES_OR_NO           FLUSH_KEYBOARD
  64.               KEY_CHECK           KEY_READ            KEY_PUT
  65.               KEY_IF_READY        SETUP_MOUSE         MOUSE_PARMS
  66.               KEY_OR_MOUSE        MOVE_MOUSE          MAKE_PIXELS
  67.               BOX_THE_MOUSE       MOUSE_CURSOR_ON     MOUSE_CURSOR_OFF
  68.               GET_STRING          KEY_DECODE          QGET_STRING
  69.               WINDOW_EDIT         WINDOW_CSTRING
  70.  
  71.  parse        PARSE_FIRST         PARSE_NEXT
  72.  
  73.  string       STRLEN1             STRLEN2             STRLEN3
  74.               LAST_CHAR           LAST_CHARC
  75.               FIRST_CHAR          FIRST_CHARC         BUFFER_SEARCH
  76.               BUFFER_SEARCHC      STR_SRCHC           LAST_STR
  77.               LEGAL_CHAR_CHECK
  78.               STR_UPPER           STR_UPPERC          STR_LOWER
  79.               STR_LOWERC          STR_CENTER          STR_LEFT
  80.               STR_RIGHT           STR_CLEANL          STR_CLEANR
  81.               STR_REMOVE          STR_CHAR_DEL        STR_CHAR_DELC
  82.               STR_REVERSE         STR_REVERSEC        STR_SWAP
  83.               STR_CLEAN           STR_CLEANC          STR_JOIN
  84.               STR_INSERT          STR_COPY            STR_COPYC
  85.               ILLEGAL_CHAR_CHECK
  86.               
  87.  system       LIBRARY_SETUP       LIBRARY_TERMINATE   FIND_CPU_TYPE
  88.               MATH_HARDWARE       KEYBOARD_SETUP      FIND_MOUSE
  89.               CHECK_ANSI          DISPLAY_INFO
  90.               DETECTVID           FIND6845            FIND_DISPLAY_SEGMENT
  91.               SPAWN_DOS           COUNT_FLOP_DRIVES   GET_DRV_TYPE
  92.               BREAK_KEY_INTERCEPT BREAK_KEY_RESTORE   BREAK_CHECK
  93.               
  94.  time         DAYS_TO_DATE        MONTH_TO_ASCII      DAY_TO_ASCII
  95.               GET_TIME            ASC_TIME            GET_DATE
  96.               GET_DAY             ASC_DATE            DATE_TO_DAYS
  97.  
  98.  
  99.    Notes:  If all registers are saved and then restored by a function,
  100.            then the outputs may be listed as "none".
  101.            
  102.            The flag register is always assumed to be changed by the
  103.            called function, and the direction flag is sometimes forced
  104.            to the "CLD" state.
  105.            
  106.            Many functions require that LIBRARY_SETUP prepare memory or
  107.            obtain hardware information first.  This is not listed as
  108.            one of the function inputs in most cases.
  109.            
  110.            All strings or text are assumed to be zero terminated unless
  111.            otherwise specified.
  112.            
  113.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(COMPRESS )
  114. shrink - compress data block
  115.  
  116.   inputs:  es:si = feed procedure ptr
  117.            es:di = store procedure ptr
  118.            dx,ax = size of block of data to be compressed
  119.  
  120.   output:  The feed procedure is called with:  ds:dx = buffer area
  121.                                                   ax = request byte count
  122.            The feed procedure returns:  ax = byte count of data placed in
  123.                                               buffer.
  124.  
  125.            The store procedure is called with:  ds:dx = buffer pointer
  126.                                                    ax = buffer size
  127.  
  128.   note:  The feed procedure is called whenever the compress module runs
  129.          out of data.  The store module is called whenever more data is
  130.          needed.  Normally, the feed and store data uses a disk file, but
  131.          if room it could be placed in memory.
  132.  
  133.          See example in file COMPRES.ASM.
  134.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(COMPRESS )
  135. expand - expand compressed data back to original state
  136.  
  137.    inputs:  es:si  = feed procedure (provides compressed data)
  138.             es:di  = store procedure (recieves uncompressed data blocks)
  139.  
  140.   output:  The feed procedure is called with:  ds:dx = buffer area
  141.                                                   ax = requested byte count
  142.            The feed procedure returns:  ax = byte count of data placed in
  143.                                               buffer.
  144.  
  145.            The store procedure is called with:  ds:dx = buffer pointer
  146.                                                    ax = buffer size
  147.  
  148.   note:  The feed procedure is called whenever the expand module runs
  149.          out of data.  The store module is called whenever more data is
  150.          needed.  Normally, the feed and store data uses a disk file, but
  151.          if room is available it could be placed in memory.
  152.  
  153.          See example in file RESTOR.ASM
  154.  
  155.          
  156.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  CONFIG )
  157. GET_SETUP - read setup file from disk
  158.  
  159.   inputs: ds:si = buffer containing default setup block
  160.  
  161.   output:  AL = 0 (setup block is ok, input block updated if file found)
  162.                 1 (setup block is bad)
  163.            AH = 0 (setup file was not found, so it was created using defaults)
  164.                 1 (setup file read from disk)
  165.  
  166.   processing: 0. allocate memory and copy default setup information.
  167.               1. build setup file name using executable plus ".CFG"
  168.               2. look for existing setup file & use if found
  169.               3. if setup not found write defaults to disk
  170.               4. parse setup block and build summary_table
  171.               5. feed color information to library
  172.  
  173.   notes:  GET_SETUP establishes the setup data block for program and
  174.           library code.
  175.  
  176.           Building a setup block requires headers and variables.  The
  177.           headers are displayed by CHANGE_SETUP and allow variables to
  178.           grouped by type.  Each variable consists of a structure which
  179.           is used to define the variable.  The header format
  180.           is "<<header text>>" followed by a zero character.  Up to
  181.           six headers can be defined.  The variable data is described
  182.           by a structure with the following format:
  183.  
  184.             struc  variable
  185.               db    ?    ;data type 1=boolean,2=hex,3=decimal,4=color,5=string
  186.               db    ?   ;data length 1=byte,2=word,4=dword, or n for string len
  187.               xx    ?   ;minimum value,used for data types 1,2,3,4 (see note1)
  188.               xx    ?   ;maximum value,used for data types 1,2,3,4 (see note1)
  189.               xx    ?   ;default setting, all data types, strings end with zero
  190.               db    ?   ;description of this variable (string) ending with zero
  191.  
  192.               note1 - the length of minimum value and maximum value fields
  193.                       depends upon the data types and data length.  It will
  194.                       be a byte for all types except 2 & 3.  For 2&3 the
  195.                       length will track the length field setting.
  196.  
  197.           The setup block must have color descriptions in the first block
  198.           and these color descriptions must be in the order needed by
  199.           library functions.  A typical setup block consisting of two sections
  200.           would look like this:
  201.   
  202.           setup_block    label    byte
  203.                db    "<<color settings>>",0
  204.                db    4,1,0,0ff,1bh,"menu bar text color",0
  205.                db       4,1,0,0ff,2bh,"menu bar select color",0
  206.                           .
  207.                           .
  208.                db       "<<setup block 2>>",0
  209.                db       1,1,0,1,0,"turn sound on",0              ;yes/no setup
  210.                db       2,1,0,0ff,0,"enter hex value",0          ;hex byte
  211.                db       3, 0,0, 8,0, 4,0, 'enter decimal word",0 ;decimal word
  212.                db       5,15,0,0,"default string",0,"enter string",0
  213.                           .
  214.                db       "<<end>>",0
  215.  
  216.          note2 - The length of strings include the zero byte at end.
  217.          note3 - For correct order and wording of color setup entries
  218.                  see sample file EDREC.ASM and EDREC.CFG.
  219.          note4 - The colors can also be changed by calling SET_LIB_COLORS 
  220.                  or writing directly to memory using the information returned
  221.                  from LIBRARY_SETUP and the file COMMON.INC.
  222.             
  223.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  CONFIG )
  224. CHANGE_SETUP - modify setup data in memory
  225.  
  226.   inputs:  none
  227.   
  228.   output:  none
  229.   
  230.   processing: 1. allow user to edit the setup buffer
  231.               2. give option to write to disk
  232.  
  233.   Notes:  The input to this routine is the setup block which
  234.           has been processed by GET_SETUP.  CHANGE_SETUP can not
  235.           be called until GET_SETUP has been executed.
  236.  
  237.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  CONFIG )
  238. WRITE_SETUP - write setup to disk
  239.  
  240.   inputs:   ds:si = setup block ptr
  241.            cx = setup block length
  242.  
  243.   output:   no carry = success
  244.            carry = problem creating the file
  245.               register changed are:  bx,dx
  246.               
  247.   processing:    1. add the checksum to buffer input
  248.                 2. build filename from executable filename with .CFG added
  249.                 3. write setup block to current directory location
  250.  
  251.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  CONFIG )
  252. SET_LIB_COLORS - set colors to be used by the library
  253.  
  254.   inputs:  al = color attributes
  255.            bx = color number (position in table)
  256.  
  257.              options available are:           defaults:
  258.                0 = menu bar text color          07h
  259.                1 = menu bar select color        70h
  260.                2 = menu bar hotkey color        0Fh         (1)
  261.                3 = submenu box color            0Fh
  262.                4 = submenu selection color
  263.                5 = msg text color
  264.                6 = msg_hyper_color
  265.                7 = pick color
  266.                8 = pick selection color
  267.                9 = box frame type (see DRAW_BOX)  -1
  268.  
  269.   outputs: none
  270.   
  271.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  272. BYTE_TO_HEX_STR - convert hex byte to two ascii characters
  273.  
  274.   inputs:    al = hex byte
  275.           ds:si = storage buffer for ascii
  276.           
  277.   output:    si = points past last store (bumped by 2)
  278.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  279. BYTE_TO_HEX_CRT - convert hex byte to ascii and display
  280.  
  281.   inputs:    al = hex byte
  282.           ds:si = storage buffer for ascii
  283.           
  284.   output:    si = points past last store (bumped by 2)
  285.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  286. DEC_STR_TO_WORD -  convert unsigned ascii string to binary word
  287.  
  288.   inputs  ds:si points    at string ending with "space" or "return"
  289.   
  290.   output  ax = binary value
  291.        si = updated to point at end of value
  292.        carry set if    error
  293.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  294. DEC_STRZ_TO_DWORD - convert numeric asciiz string to double word value
  295.  
  296.  inputs:  ds:si = string ptr (string ends with zero)
  297.  
  298.  output:  if no carry, dx,ax = number (ax is low word)
  299.           if carry, error occurred
  300.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  301. DEC_STR_TO_DWORD - convert string to double word
  302.  
  303.  inputs:  ds:si = string ptr
  304.              cx = string length
  305.              
  306.  output:  if no carry, dx,ax = number (ax is low word)
  307.           if carry, error occurred
  308.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  309. DWORD_TO_DEC_STR - convert a long integer value to an ASCIIZ string
  310.  
  311.   inputs:    DS:[SI] - pointing to a buffer space
  312.              DX:AX = long integer value
  313.              LONG_TO_STR requires a 12-byte (or greater) buffer
  314.              
  315.   output:    ASCIIZ string at DS:[SI]; numerals are right-justified
  316.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  317. DWORD_TO_HEX_STR - hex double word to ascii
  318.  
  319.  INPUTS: DX,AX = HEX
  320.  
  321.  OUTPUTS: si points past last byte stored
  322.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  323. DWORD_TO_HEX_CRT - hex double word to ascii and display
  324.  
  325.  INPUTS: DX,AX = HEX
  326.  
  327.  OUTPUTS: NONE
  328.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  329. DWORD_TO_DEC_STRX - convert dword to decimal ascii with formatting
  330.   inputs: dx,ax = binary dword, dx=high word, ax=low word
  331.           ds:di = pointer to end of storage buffer.
  332.   output:   di = pointer to start (left side) of decimal string.
  333.  
  334.   note:  The storage buffer must be initialized with all spaces if
  335.          leading blanks are utilized.
  336.  
  337.          This routine right justifies the decimal ascii in a buffer
  338.          and adds commas between each grouping of three digits.
  339.          Normally, this routine is used to display numbers in columns
  340.          with right edge lined up.
  341.  
  342.          Beware, the input buffer pointer must point to the end of the
  343.          buffer and not the start.
  344.  
  345.          This routine can be used to display right or left justified
  346.          numbers by using the buffer start or returned DI.
  347.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  348. DWORD_TO_DEC_CRTX - convert dword to decimal ascii and display
  349.   inputs: dx,ax = binary dword, dx=high word, ax=low word
  350.   output: none
  351.  
  352.   note:  Display cursor should be at right end of area for decimal value.
  353.          The value is displayed from right to left and commas added to
  354.          separate every 3 characters.
  355.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  356. HEX_STR_TO_BYTE - convert 2 hex ascii characters to 1 hex byte
  357.  
  358.    inputs: ds:si points at hex data
  359.    
  360.    output: no carry - al = hex byte
  361.               carry - bad input data
  362.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  363. HEX_STR_TO_WORD - convert 4 hex ascii characters to 2 hex bytes
  364.  
  365.    inputs: ds:si points at hex data
  366.    
  367.    output: no carry - al = hex word
  368.               carry - bad input data
  369.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  370. WORD_TO_DEC_STR - convert an integer value to an ASCIIZ string
  371.  
  372.   inputs:    DS:[SI] pointing to a buffer space
  373.              (WORD_TO_STR) AX = integer value
  374.              WORD_TO_STR requires a 7-byte (or greater) buffer;
  375.              
  376.   output:    ASCIIZ string at DS:[SI]; numerals are right-justified
  377.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  378. WORD_TO_DEC_CRT - convert word to decimal ascii and display
  379.  
  380.   inputs:  ax = binary value
  381.            di = display offset
  382.            ch = color
  383.            
  384.   outputs: none
  385.  
  386.   registers changed:  ax,dx
  387.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  388. WORD_TO_HEX_STR - convert hex word to four ascii characters
  389.  
  390.   inputs:    ax = hex word
  391.           ds:si = storage for 4 ascii characters
  392.           
  393.   output:    si = pointer past last store (bumped by 4)
  394.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( CONVERT )
  395. WORD_TO_HEX_CRT - hex word to ascii and display it
  396.  
  397.   inputs:    ax = hex word
  398.           ds:si = storage for 4 ascii characters
  399.           
  400.   output:    si = pointer past last store (bumped by 4)
  401.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(DATABASE )
  402. dbase_init - open and initialize an existing or new database
  403.  
  404.  inputs:  ds:dx = ptr to asciiz file name
  405.            
  406.  output:  no carry + al = 0 (successfully opened an existing database)
  407.              carry + al = 1 (new data base created)
  408.              carry + al = 3 (insufficient memory to open database)
  409.              carry + al = 4 (disk error)
  410.             bx = selector needed to access database (segment)
  411.             cx = number of records read initially, if zero this is null file.
  412.             
  413.  processing: 1. allocate memory to handle database information
  414.              2. open the file or create it if necessary
  415.              3. initialize the data area
  416.              4. read the first block of data
  417.  
  418.  notes:  The database routines are usually called in the following
  419.       order:        1. DBASE_INIT
  420.                 2. database read/write routines
  421.             3. dbase_close
  422.          The file EDREC.ASM shows examples of database functions.
  423.          The file HYPER.ASM shows an example of using database records.
  424.                      
  425.  
  426.  overview: The database routines can handle varable length data records
  427.            which end with a zero byte.  The zero byte can not occur within
  428.            the data area of any record.  All data is referenced by record
  429.            number which is kept current.  When data is inserted, all record
  430.            numbers following the inserted data are increased by one. 
  431.            Conversly, when a record is deleted, all the record numbers
  432.            following the deleted record are decreased by one.
  433.            Changes or additions to a data file are kept in memory until
  434.            memory is filled with changes, at that time they are written
  435.            to the file.  They are also written if a file access is needed
  436.            outside the range of record numbers kept in memory.  finally,
  437.            when the data file is closed by DBASE_CLOSE, all changes are
  438.            written to the data file.
  439.  
  440.  limitations: Record numbers must be within the range 1-65534.
  441.  
  442.               The maximum size of a record is 8181 bytes.
  443.               
  444.               Records can contain data bytes with the values of 01h to 0ffh,
  445.               but not a value of 00h.  Since ASCII data does not have any
  446.               00h values it is the easiest to use with database records.
  447.  
  448.               Opening a database allocates about 36,000 bytes of memory
  449.               and requires that two files be opened.  Multiple database's
  450.               can be opened as long as enough memory and file handles
  451.               are available.
  452.               
  453.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(DATABASE )
  454. DBASE_READ - read specific record from the database.
  455.  
  456.  inputs: es = selector from DBASE_INIT
  457.          dx = record# to read
  458.  
  459.  output: no carry + al = 00 - if successful, cx=read amount
  460.             carry + al = 04 - record not here, could be no records are present
  461.             carry + al = 02 - selector bad or database corrupted.
  462.             carry + al = 07 - record was too big to fit in memory
  463.             carry + al = 08 - unknown error
  464.       es:si = ptr to record read (valid only if al=0)
  465.       cx = record length including separator character. (present if al=0)
  466.  
  467.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(DATABASE )
  468. dbase_read_next - read next sequential record.
  469.  
  470.  inputs:    es = selector from DBASE_INIT
  471.  
  472.  output: no carry or al = 00 - success
  473.             carry or al = 01 - record not here, could be no records are present
  474.             carry or al = 02 - selector bad or database corrupted.
  475.       es:si = ptr to record read (valid only if al=0)
  476.       cx = record length including separator character. (present if al=0)
  477.          dx = record number
  478.  
  479.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(DATABASE )
  480. dbase_read_prev - read previous record. (write operations do not affect)
  481.  
  482.  inputs:     es = selector from DBASE_INIT
  483.  
  484.  output: no carry or al = 00 - success
  485.             carry or al = 01 - record not here, could be no records are present
  486.             carry or al = 02 - selector bad or database corrupted.
  487.       es:si = ptr to record read (valid only if al=0)
  488.       cx = record length including separator character. (present if al=0)
  489.          dx = record number
  490.  
  491.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(DATABASE )
  492. dbase_append - append this record to end of database
  493.  
  494.  inputs:     es = selector from DBASE_INIT
  495.           ds:di = source data buffer
  496.           cx = length of record excluding the separator character
  497.           
  498.  output:  no carry,  al = 0 (success)
  499.             carry or al = 02 - selector bad or database corrupted.
  500.                      dx = record # assigned
  501.  
  502.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(DATABASE )
  503. dbase_insert - insert this record before specific record
  504.  
  505.  inputs:      es = selector from DBASE_INIT
  506.         ds:di = source data buffer
  507.            cx = length of record excluding the separator char if present
  508.               dx = record number to insert before
  509.  
  510.  output:  no carry,  al = 0 (success)
  511.             carry or al = 01 - record not here, could be no records are present
  512.             carry or al = 02 - selector bad or database corrupted.
  513.                      dx = record number assigned
  514.           
  515.  Note: Inserts are placed in front of the record number input. 
  516.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(DATABASE )
  517. dbase_replace - replace data for a specific record
  518.  
  519.  inputs:     es = selector from DBASE_INIT
  520.           ds:di = source data buffer
  521.           cx = length of record excluding the separator char if present
  522.              dx = record number to insert before
  523.  
  524.  output:  no carry,  al = 0 (success)
  525.             carry or al = 01 - record not here, could be no records are present
  526.             carry or al = 02 - selector bad or database corrupted.
  527.  
  528.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(DATABASE )
  529. DBASE_REMOVE - delete specific record
  530.  
  531.  inputs:      es = selector from DBASE_INIT
  532.            dx = record number to delete
  533.  
  534.  output:  no carry,  al = 0 (success)
  535.             carry or al = 01 - record not here, could be no records are present
  536.              
  537.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(DATABASE )
  538. dbase_close - close & write any pending data to file
  539.  
  540.  inputs:      es = database selector returned by DBASE_INIT
  541.  
  542.  output:  no carry,  al = 0 (success)
  543.             carry or al = 02 - selector bad or database corrupted.
  544.  
  545.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(DATABASE )
  546. dbase_delete - delete dbase file
  547.  
  548.   inputs:       ds:dx = asciiz file name ptr
  549.   
  550.   output:    carry set if error, error code from DOS function 41h
  551.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  552. FILE_COPY - copy a file
  553.  
  554.   inputs:    DS:[SI] = address of source filename
  555.              ES:[DI] = address of destination filename
  556.              Both filenames must be ASCIIZ strings.
  557.              
  558.   output:    if CF = 0, no problem
  559.              if CF = 1, AX = DOS error code (AX = -1 if insufficient memory)
  560.              All registers unchanged except for -AX-
  561.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  562. FILE_SIZE1 - find an open file's size
  563.  
  564.   inputs:    BX = file handle
  565.   
  566.   output:    if CF = 0, DX:AX = file size (low word in AX)
  567.              if CF = 1, AX = DOS error code
  568.              
  569.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  570. FILE_SIZE2 - find a closed file's size
  571.  
  572.   inputs:    DS:DX = pointer to file name asciiz string
  573.   
  574.   output:    if CF = 0, DX:AX = file size (low word in AX)
  575.              if CF = 1, AX = DOS error code
  576.              
  577.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  578. FILE_COUNT - counts the number of files matching an ASCIIZ file spec string.
  579.  
  580.   inputs:    DS:[DX] pointing to file spec string
  581.              CX = file attributes
  582.              
  583.   output:    AX = number of files matching the file spec string
  584.  
  585.   notes:     The file spec string may include the '*' and '?' wildcards.
  586.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  587. FILE_FLUSH - flushes the DOS output buffer for specified handle
  588.  
  589.   inputs:    BX = file handle
  590.              flushing the buffer guards against data loss in case power
  591.              outages.
  592.              
  593.   output:    if CF = 0, no error; function successful
  594.              if CF = 1, AX = DOS error code
  595.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  596. FILE_EXIST - determines if a file exists and can be opened
  597.  
  598.   inputs:    DS:[DX] pointing to ASCIIZ filename
  599.   
  600.   output:    if CF = 0, file exists
  601.              if CF = 1, AX = DOS error code
  602.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  603. EXPAND_FILENAME - Expand a file string to the full path including drive.
  604.                   This is useful for user entered data which needs to
  605.                   be made consistent for processing.  See DECODE_FILENAME.
  606.  
  607.   inputs:    DS:[SI] pointing to a filename; the filename may contain
  608.                      drive specification and/or complete or partial path name.
  609.                      Drive specification and path name not required.
  610.                      Path string is terminated with a zero (null) character.
  611.                      
  612.   outputs:  if no carry then,
  613.              DS:[SI] pointing to the full DRIVESPEC:\PATH\FILENAME
  614.              CX = length of full filename
  615.             if carry is set then filename is bad
  616.  
  617.   Note:  The file name is expanded and will overwrite the file name input.
  618.          Thus, the file name which is input needs to be in a buffer area
  619.          which will accommodate the expansion.       
  620.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  621. DECODE_FILENAME - return pointers to major portions of file name
  622.  
  623.    inputs: ds:bx = pointer to file name, use EXPAND_FILENAME to format first
  624.    
  625.    output: if no carry then,
  626.             ds:si = pointer to path
  627.             ds:di = pointer to filename
  628.                cx = path length
  629.                dx = filename length
  630.                ah = drive letter
  631.                al = drive number
  632.            if carry, then filename is bad.
  633.  
  634.   Note: The input string should be:  <drive letter>:/<path>/<filename>0
  635.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  636. FIND_HOME_PATH - find the full path and filename of the executing program
  637.  
  638.   inputs:    nothing
  639.   
  640.   output:    ES:[DI] = pointer to the the name of the executing program
  641.                  CX = length of path string.
  642.  
  643.   note:      The filename returned is an ASCIIZ string, and may be mixed
  644.              upper- and lower-case characters.
  645.              
  646.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  647. GET_PATH - search environment for start of path information string
  648.  
  649.   inputs:    nothing
  650.   
  651.   output:     ES:DI = pointer to "PATH=" portion of path string.
  652.                  CX = length of path
  653.  
  654.   note:  The path string consists of "PATH=" followed by path entries.
  655.          Each path entry is separated with ";" and the last one is
  656.          followed by a null character (00h).  ES:DI points at
  657.          the start of "PATH=".                 
  658.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  659. CHANGE_PATH - switch to new directory, but save current path first
  660.  
  661.   inputs:  es:bx - points to new path
  662.   
  663.   outputs: old_path has original path
  664.         carry set if dos error
  665.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  DISK   )
  666. RESTORE_PATH - switch to directory saved by CHANGE_PATH
  667.  
  668.   inputs: none
  669.   
  670.   output: carry set if dos error
  671.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  672. PUT_CRT_CHR - display single character
  673.               write character (ax) to display at row/column (dx)
  674.  
  675.   inputs: ax = char & color
  676.           dx = address
  677.  
  678.   outputs:es = display segment
  679.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  680. GET_CRT_CHR -  read character and attribute from text screen
  681.  
  682.   inputs:    DH = screen row
  683.              DL = screen column
  684.  
  685.   output:    AH = color attribute
  686.              AL = ASCII character code
  687.  
  688.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  689. REPEAT_PUT_CRT - displays a single char CX times.
  690.  
  691.   inputs:  ax = char (ah=color attribute, al=ascii character)
  692.            dx = display location (dh=row, dl=column)
  693.            cx = count
  694.  
  695.  output:  none
  696.  
  697.  notes:  The character and color (ax) are displayed starting at
  698.          location (dx) until count (cx) is counted down to zero.
  699.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  700. PUT_CRT_BLK - copies a string to video memory buffer, with selected
  701.               color attribute;
  702.  
  703.   inputs:         CX = maximum number of characters to print
  704.              DS:[SI] = pointer to first character of string
  705.              ES:[DI] = pointer to video buffer
  706.                   AH = color attribute
  707.                   DF = 0 (clear direction flag with CLD)
  708.              
  709.   output:    ES:[DI] = pointer to next video buffer display point
  710.              DS:[SI] = pointer to byte following last one displayed
  711.  
  712.   notes:  registers changed = al,cx,di,si,flags
  713.  
  714.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  715. VERTICAL_REPEAT_CHR - repeat one or more columns of a character vertically
  716.  
  717.   inputs: ax = char
  718.           dx = row/col
  719.           bx = increment to next repeat
  720.           cx = char repeat length
  721.           si = operation(rows) repeat count
  722.  
  723.   output: registers changed = bx,si,di 
  724.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  725. TABULAR_DRAW - Subroutine to draw using a table   tabular_draw
  726.  
  727.     inputs:    ah = color
  728.             ds:bx = table ptr
  729.                     table =    db repeat count (negative for columns)
  730.                                db char
  731.                                db column
  732.                                db row
  733.                         above blocks are repeated until ( dw -1) is found.
  734.  
  735.   output:  registers changed = ax,bx,cx,dx,si,di
  736.  
  737.   notes:  Each table entry can draw a line either horizontally or
  738.           vertically.
  739.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  740. CLEAR_SCREEN - fill screen with specified character and color
  741.  
  742.   inputs:    AH = color attribute
  743.              AL = fill character
  744.              
  745.   output:    nothing
  746.  
  747.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  748. DISPLAY_STRING - print string directly to video buffer.
  749.  
  750.   inputs: DS:[SI] = pointer to the string
  751.              DH = screen row, DL = screen column
  752.              AH = color attribute
  753.              
  754.   output:    nothing
  755.  
  756.   notes:  String must be terminated by a NUL character.
  757.           cr/lf characters are handled & wrap to original column.
  758.  
  759.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  760. DISPLAY_STRING_FILL - display string to screen at specified position.
  761.  
  762.   inputs:   DS:[SI] = pointer to the string
  763.              cx = maximum length of display line including fill at end
  764.              DH = screen row, DL = screen column
  765.              AH = color attribute
  766.              
  767.    output:   nothing
  768.    
  769.    notes:   If string is shorter than the display line length (cx), then
  770.             the remainder of the line is cleared.
  771.  
  772.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  773. DISPLAY_STRING_LIST -  display a list of strings
  774.  
  775.  
  776.   inputs:  ds:bx points at table of offsets
  777.            ah= color
  778.  
  779.   output: none
  780.  
  781.   notes:  ds:bx points to a table of pointers.  The end of the table
  782.           is indicated by setting an entry to -1.  Each table entry
  783.           points to an asciiz string.
  784.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  785. CLEAR_WINDOW - fill area of screen
  786.  
  787.   inputs:    dx = window position dh=row  dl=column
  788.              bx = window size    bh=rows in window  bl=columns in window
  789.              AH = color attribute
  790.              AL = fill character
  791.              
  792.    output:   nothing
  793.  
  794.    notes:  The dx,bx registers define a box on the screen in standard
  795.            library format (see DRAW_BOX).
  796.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  797. DRAW_BOX -  draw a box on screen
  798.  
  799.   inputs:    dx = box address    dh=row    dl=column
  800.          bx = box size   dh=rows in box  dl=columns in box
  801.              AH = color attribute
  802.          AL = box frame type  0=single line
  803.                           1=double line
  804.   output: none
  805.  
  806.   notes:  The center of the box is cleared as it is drawn.
  807.           Box parameters are not checked for illegal sizes so beware.
  808.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  809. WINDOW_STRING -  display string in window.
  810.  
  811.   inputs: DS:[SI] = pointer to the string
  812.            dx = starting row(dh)  starting column(dl)
  813.            bx = box total rows(bh)  box total columns(bl)
  814.                AH = color attribute
  815.                
  816.   outputs:   none
  817.  
  818.   notes:  String must be terminated with null character.
  819.           Strings will wrap if cr/lf is found or edge of box is encountered.
  820.           Any area to right of string is cleared up to edge of box.
  821.           String which wrap will try not to split words.
  822.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  823. BOX_RIGHT - move box parameters right
  824.  
  825.   inputs:  dx = box display address,  dh=row  dl=column
  826.            bx = box size,  bh=rows in box  bl=columns in box
  827.            
  828.   output:  dx = box row (dh) and box column (dl) moved one position
  829.            bx = box size, number of rows (bh), number of columns (bl)
  830.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  831. BOX_LEFT -  move box parameters left
  832.  
  833.   inputs:  dx = box display address,  dh=row  dl=column
  834.            bx = box size,  bh=rows in box  bl=columns in box
  835.            
  836.   output:  dx = box row (dh) and box column (dl) moved one position
  837.            bx = box size, number of rows (bh), number of columns (bl)
  838. comment  
  839.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  840. BOX_UP - move box parameters up one position
  841.  
  842.   inputs:  dx = box display address,  dh=row  dl=column
  843.            bx = box size,  bh=rows in box  bl=columns in box
  844.            
  845.   output:  dx = box row (dh) and box column (dl) moved one position
  846.            bx = box size, number of rows (bh), number of columns (bl)
  847.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  848. BOX_DOWN - move box parameters down one position
  849.  
  850.   inputs:  dx = box display address,  dh=row  dl=column
  851.            bx = box size,  bh=rows in box  bl=columns in box
  852.            
  853.   output:  dx = box row (dh) and box column (dl) moved one position
  854.            bx = box size, number of rows (bh), number of columns (bl)
  855.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  856. BOX_EXPAND - expand box one position in all directions
  857.  
  858.   inputs:  dx = box display address,  dh=row  dl=column
  859.            bx = box size,  bh=rows in box  bl=columns in box
  860.            
  861.   output:  dx = box row (dh) and box column (dl) moved one position
  862.            bx = box size, number of rows (bh), number of columns (bl)
  863.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  864. BOX_SHRINK - shrink box parameters one position in all directions
  865.  
  866.   inputs:  dx = box display address,  dh=row  dl=column
  867.            bx = box size,  bh=rows in box  bl=columns in box
  868.            
  869.   output:  dx = box row (dh) and box column (dl) moved one position
  870.            bx = box size, number of rows (bh), number of columns (bl)
  871.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  872. GET_ANSI_COLOR - get color attribute used by ANSI driver.
  873.  
  874.   inputs:    none
  875.   output:    AH = color attribute
  876.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  877. CURSOR_ - Move cursor and set size to standard underscore.
  878.  
  879.   inputs:    DH = row
  880.              DL = column
  881.              
  882.   outputs:   register -ax- is modified
  883.   
  884.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  885. SHOW_CURSOR - move cursor to (row, col) and update cursor shape
  886.  
  887.   inputs:    DH = row offset from top of screen
  888.              DL = column offset from left side
  889.  
  890.   outputs:   register -ax- modified
  891.  
  892.   notes:     Cursor shape is underscore if INSERT is off, large block
  893.              if INSERT is on.
  894.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  895. HIDE_CURSOR - make hardware cursor invisible at present location
  896.  
  897.   inputs:    none
  898.   outputs:   none
  899.  
  900.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  901. BLINK_ON:  enable blinking attributes
  902.  
  903.   inputs: none
  904.   output: none
  905.  
  906.   notes:  The opposite of blink is intensified colors.  The normal default
  907.           is blink on.
  908.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  909. BLINK_OFF:  disable blinking attributes
  910.  
  911.   inputs: none
  912.   output: none
  913.  
  914.   note: Blink off turns intensified color selection on.  The default at
  915.         boot time is blink on.
  916.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  917. save_window - save area of display in memory buffer
  918.  
  919.   inputs: dx=box left corner (dh=row,dl=column)
  920.           bh=rows in window
  921.       bl=columns in window
  922.       
  923.   output: none
  924.   
  925.   processing: save up to three window areas which can be restored
  926.            with restore_window.  The memory manager is called
  927.            to allocate room to store windows saved.
  928.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  929. restore_window - restore a previously saved area of display
  930.  
  931.   inputs: none
  932.   
  933.   output: carry set if error
  934.           all registers are saved
  935.   
  936.   processing: restore uses information in save_window to restore the last
  937.            window saved.  Up to three windows can be saved and then
  938.            restored in reverse order.
  939.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  940. DISK_TO_CRT - loads a screen image file saved by CRT_TO_DISK
  941.  
  942.   inputs:    DS:[DX] = address of ASCIIZ filename
  943.   
  944.   outputs:   if CF = 1, AX = MS-DOS file I/O error code
  945.              if CF = 0, no error
  946.              registers modified = AX            
  947.  
  948.  notes:     The input file is assumed to be closed when DISK_TO_CRT is
  949.             called, and is left closed upon exit.
  950.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( DISPLAY )
  951. CRT_TO_DISK - saves a screen image as a file
  952.  
  953.   inputs:    DS:[DX] = address of ASCIIZ filename
  954.   
  955.   outputs:   if CF = 1, AX = MS-DOS file I/O error code
  956.              if CF = 0, no error
  957.              registers modified = AX
  958.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  ERROR  )
  959. LIB_ERROR_HANDLER - handle pre defined library errors
  960.  
  961.   inputs:     al = error number (see error_index)
  962.           ah = flags 80h = fatal_error, abort after display
  963.                          40h = non_fatal1, return to retry
  964.                          20h = non_fatal2, return after any key press
  965.                          10h = fatal_return, fatal error but return after key
  966.                          08h = spare
  967.                          04h = spare
  968.              02h = spare
  969.              01h = spare
  970.  
  971.   output:  displayed error message as follows:
  972.            1 - Incompatible display mode
  973.            2 - Code error, Contact program author for possible
  974.                problem resolution
  975.            3 - Disk read error, Press any key to continue
  976.            4 - Fatal disk error, Press any key
  977.            5 - Out of memory, Press any key to abort current operation
  978.            6 - Path change failed, Press any key
  979.            7 - insufficient DOS memory to run program,
  980.                Press any key to abort.
  981.            8 - Error in finding/reading quote file QUOTE.DAT
  982.            9 - Memory manager transfer error.  This is usually
  983.                a programming error.  Contact the author for assistance.
  984.           10 - Open of above file failed, possibly the file does not
  985.                exist or is not in correct directory.
  986.           11 - The program configuration (.CFG) file is missing an <end>
  987.                statement.   press any key to continue
  988.  
  989.   note:  LIB_ERROR_HANDLER is intended for library use only, but can be
  990.          called from application.               
  991.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  ERROR  )
  992. error_handler - handle fatal errors
  993.  
  994.   inputs:     ds:si = error text terminated with null character (00).
  995.                  ah = flags 80h - fatal_error, abort after display
  996.                             40h - non_fatal1, return to retry
  997.                             20h - non_fatal2, return after any key press
  998.                             10h - fatal_return, fatal error but return after key
  999.                             08h - spare
  1000.                 04h - spare
  1001.                 02h - spare
  1002.                 01h - spare
  1003.  
  1004.   output:    ax = last keypress if a return was requested.
  1005.  
  1006.   notes:  If the abort option is requested, the library will be closed and
  1007.           the DOS return call executed.
  1008.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  ERROR  )
  1009. error_prime - setup error handler with additional error information
  1010.  
  1011.   inputs:  ds:bp = table of additional errors used by ERROR_TABLE_HANDLER
  1012.            ds:di = ptr to file name for use by ERROR_FILE_HANDLER
  1013.  
  1014.   output:  none
  1015.  
  1016.   note:  If either ERROR_TABLE_HANDLER or ERROR_FILE_HANDLER are used
  1017.          they must first be primed with the error information.  Error
  1018.          files can be built with EDREC and the first record will be
  1019.          error #1.  Similarly a table can be built in memory which
  1020.          consists of a list of pointers to text strings.         
  1021.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  ERROR  )
  1022. ERROR_TABLE_HANDLER - handle errors described in table provided by programmer
  1023.  
  1024.   inputs:     ds:si = error text
  1025.            ah - flags 80h = fatal_error, abort after display
  1026.                           40h = non_fatal1, return to retry
  1027.                           20h = non_fatal2, return after any key press
  1028.                           10h = fatal_return, fatal error but return after key
  1029.                           08h = spare
  1030.               04h = spare
  1031.               02h = spare
  1032.               01h = spare
  1033.  
  1034.   output:  none
  1035.  
  1036.   Note: ERROR_PRIME must be caller before this routine is accessed
  1037.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  ERROR  )
  1038. ERROR_FILE_HANDLER - handle errors described in file provided by programmer
  1039.   inputs:     ds:si = error text
  1040.            ah - flags 80h = fatal_error, abort after display
  1041.                           40h = non_fatal1, return to retry
  1042.                           20h = non_fatal2, return after any key press
  1043.                           10h = fatal_return, fatal error but return after key
  1044.                           08h = spare
  1045.               04h = spare
  1046.               02h = (future) error_text, ds:bp has message
  1047.               01h = (future) error_value, bp has error number
  1048.  
  1049.   output:  none
  1050.  
  1051.   Note: ERROR_PRIME must be called before this routine is accessed
  1052.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  ERROR  )
  1053. SOUND_ON - Enable sounds from BEEP and ONE_BEEP
  1054.  
  1055.   inputs: none
  1056.   output: none
  1057.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  ERROR  )
  1058. SOUND_OFF - Disable sounds from BEEP and ONE_BEEP
  1059.  
  1060.   inputs: none
  1061.   output: none
  1062.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  ERROR  )
  1063. one_beep - beep once at 200hz for fraction of a second
  1064.  
  1065.   inputs: none
  1066.   output: none
  1067.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  ERROR  )
  1068. BEEP make sound for number of milliseconds.
  1069.  
  1070.   inputs:  bx = frequency in HZ
  1071.            dx = timer ticks
  1072.   outputs: none
  1073.  
  1074.   note:  Each timer tick is about 1/5 of a second.
  1075.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1076. FLOAT_OPEN - open the floating point module & hardware for use
  1077.  
  1078.   INPUTS:  bx = number of tokens (variables) needed by program
  1079.   
  1080.   OUTPUT:  carry set signals error ( no memory ).
  1081.  
  1082.   notes:
  1083.   
  1084.           Using this library is different than normal 8087 chip
  1085.           programming.  All numbers (variables) are first assigned
  1086.           to tokens, then they can be manipulated.  When all
  1087.           calculations are finished the tokens can be extracted by
  1088.           convert to binary or text.  Thus, the normal sequence of
  1089.           operations is:
  1090.  
  1091.           1. call library_setup to reserve space for variables (tokens)
  1092.           2. input all tokens as binary values or text strings using
  1093.              TEXT_IN,BINARY_IN calls.
  1094.           3. perform all calculations using add,sub,div,etc. calls.
  1095.           4. extract results using TEXT_OUT,BINARY_OUT calls.
  1096.  
  1097.           The FLOAT_OPEN and FLOAT_CLOSE are normally handled by
  1098.           calls to LIBRARY_OPEN and LIBRARY_CLOSE.
  1099.           
  1100.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1101. FLOAT_CLOSE - release the memory allocated by FLOAT_OPEN
  1102.  
  1103.    inputs:  none
  1104.    outputs: none
  1105.  
  1106.    note:  The FLOAT_OPEN and FLOAT_CLOSE are normally handled by
  1107.           calls to LIBRARY_OPEN and LIBRARY_CLOSE.
  1108.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1109. BINARY_IN - input a value to the floating point module
  1110.  
  1111.   INPUTS:  dx,ax = signed 32 bit number
  1112.            bx    = token number to use for this number. (0-x)
  1113.            
  1114.   OUTPUT:  none
  1115.  
  1116.   NOTE:  The token number must be within the range of tokens reserved
  1117.          by LIBRARY_OPEN or FLOAT_OPEN.  No error checking is performed.
  1118.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1119. BINARY_OUT - get a binary value from the floating point module
  1120.  
  1121.   INPUTS:  bx = token number
  1122.   
  1123.   OUTPUT:  dx,ax = signed 32 bit number
  1124.            carry = overflow, number not valid
  1125.  
  1126.   NOTE:  The token number must be within the range of tokens reserved
  1127.          by LIBRARY_OPEN or FLOAT_OPEN.  No error checking is performed.
  1128.            
  1129.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1130. FMOVE - move a floating value from one token to another
  1131.  
  1132.   inputs:  ax = from token
  1133.            bx = to token
  1134.  
  1135.   output:  none
  1136.  
  1137.   note:  The token number must be within the range of tokens reserved
  1138.          by LIBRARY_OPEN or FLOAT_OPEN.  No error checking is performed.
  1139.              
  1140.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1141. F_SUBTRACT - subtract two floating numbers
  1142.  
  1143.   INPUTS:   token(ax) - token(bx) -> token(cx)
  1144.             ax = token of operand1
  1145.             bx = token of operand2
  1146.             cx = token of accumulator (result)                      
  1147.   
  1148.   OUTPUT:   token(cx) has result
  1149.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1150. F_ADDITION - add two floating numbers
  1151.  
  1152.   INPUTS:   token(ax) + token(bx) -> token(cx)
  1153.             ax = token of operand1
  1154.             bx = token of operand2
  1155.             cx = token of accumulator (result)                      
  1156.   
  1157.   OUTPUT:   token(cx) has result
  1158.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1159. FCOMP - compare two floating point numbers
  1160.  
  1161.   INPUTS:    token(ax) compared to token(bx)
  1162.   
  1163.   OUTPUT:    ax -1 (ax bigger bx)
  1164.                  0 (ax = bx)
  1165.                  1 (ax less bx)
  1166.                  (also sets flags for JE,JNE,JG,JGE,JL,JLE)
  1167.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1168. F_MULTIPLY - multiply two tokens
  1169.  
  1170.   INPUTS:   token(ax) x token(bx) -> token(cx)
  1171.             ax = token of operand1
  1172.             bx = token of operand2
  1173.             cx = token of accumulator (result)                      
  1174.  
  1175.   OUTPUT:   token(cx) has result
  1176.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1177. F_DIVIDE - divide one floating number by another
  1178.  
  1179.   INPUTS:   token(ax) / token(bx) -> token(cx)
  1180.             ax = token of operand1
  1181.             bx = token of operand2
  1182.             cx = token of accumulator (result)                      
  1183.  
  1184.   OUTPUT:   token(cx) has result
  1185.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1186. ROUND - round floating number to nearest 1/100
  1187.  
  1188.   INPUTS:  ax = token of number to be scaled
  1189.   
  1190.   PROCESSING:  token * 100 -> integer /100
  1191.  
  1192.   NOTE:  This function is intended for financial calculations which must
  1193.          be rounded to nearest penny.  The round function will round up
  1194.          if any value is greater than .xx5
  1195.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1196. TEXT_OUT - convert floating value to text string
  1197.  
  1198.   INPUTS:    token(ax) of number to be converted.
  1199.              cl = size of output buffer
  1200.              ch = number of places to right of decimal
  1201.              es:di = storage point
  1202.              
  1203.   OUTPUT:    es:di ponts at text
  1204.  
  1205.   NOTE:  The size of the output buffer must be large enough to handle
  1206.          the number and must be larger than the input value in register
  1207.          ch.  If errors are found the output buffer is filled with
  1208.          "#" characters to indicate that something is wrong.
  1209.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1210. TEXT_IN - convert a text string to floating point and assign token
  1211.  
  1212.   INPUTS:    es:di = pointer to text string ending with null character.
  1213.                 ax = token number to assign to text (0-x)
  1214.                 
  1215.   OUTPUT: errors in the text string will result in a value of zero being
  1216.           entered.
  1217.  
  1218.   NOTE:  Leading spaces or zeros are ignored in the input text string.
  1219.          The number can have a sign of "+" or "-".
  1220.          The number can have an exponent specified by using "E" and value
  1221.          or putting a decimal point "." in the number.        
  1222.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  FLOAT  )
  1223. FLOAT_SET - signal the presence of floating point hardware
  1224.  
  1225.   INPUTS:  al = lib_info.math_chip setting  (0=no chip  1=chip here)
  1226.   
  1227.   OUTPUT:  none
  1228.   
  1229.   Note:  This function not used by library at present.
  1230.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  MEMORY )
  1231. MEM_OPEN - interrogate memory and setup database.
  1232.  
  1233.   inputs:  none
  1234.  
  1235.   output:  no carry = success, ax=total 1k blocks allocated
  1236.         carry = error/warning, if ax=7 DOS memory was not found.
  1237.                       ax=2 fatal programming error
  1238.  
  1239.  
  1240.   processing: 1. determine memory available and setup database
  1241.            2. allocate all available memory
  1242.  
  1243.   Note: DOS memory is required for many library functions so
  1244.         it must be available.  See sample programs for method
  1245.         needed to make DOS memory available.
  1246.  
  1247.         This function is called once at the start of a program.
  1248.     The Library_setup function calls mem_open, so it should
  1249.     not need to be called directly.
  1250.  
  1251.         The following calls still need MEM_OPEN & MEM_CLOSE, but
  1252.     allow the MEM_PUT & MEM_GET calls to be avoided.
  1253.  
  1254.         DOS_MEM_ALLOCATE - returns segment for direct writes to
  1255.                            allocated memory
  1256.         DOS_MEM_RELEASE  - releases memory allocated with DOS_MEM_ALLOCATE
  1257.  
  1258.         The memory manager utilizes DOS,XMS, and EMS memory and isolates
  1259.         the caller from memory manipulation.  All interfaces with memory
  1260.         can be handled through memory manager calls.
  1261.  
  1262.         The mem_open,mem_allocate, and mem_close are required calls if any
  1263.     part of the memory manager is utilized. For most efficient
  1264.     memory allocation always let the memory manager decide where to
  1265.     allocate memory from, and then use only the memory manager calls
  1266.     to transfer data.  This strategy allows a program to work if any
  1267.     of the three types of memory is available.
  1268.  
  1269.     LIMITATIONS - The largest block which can be allocated for use
  1270.                       is 64k
  1271.             - The maximum number of allocations active at once
  1272.               is set to 50.  Contact author to increase/decrease
  1273.             - The smallest allocation unit is 1 word
  1274.                     - The maximum amount of memory which can be managed
  1275.                       is about 32mega bytes
  1276.  
  1277.        Before doing an exec call to DOS it is necessary to do a mem_close
  1278.        to make memory available.  Then, do a mem_open upon return.  The
  1279.        library function SPAWN_DOS is the only function that does an exec
  1280.        call to DOS.  After the mem_close and mem_open sequence all previous
  1281.        data is lost.
  1282.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  MEMORY )
  1283. MEM_ALLOCATE - allocate a block of memory.
  1284.  
  1285.   inputs:     dx,ax=number of bytes to allocate, dx=high word ax=low word
  1286.               bx=allocation method, 0=normal allocation
  1287.                                     1=only allocate DOS memory
  1288.  
  1289.   outputs:   no carry  bx=memory mgr handle, use to read/write/release
  1290.          carry     insufficient memory, or too many allocations active
  1291.                        or -bx- not set correctly
  1292.  
  1293.   note:   This function is called each time a new block of memory is needed.
  1294.           If register BX is set to normal allocation, then the MEM_GET and
  1295.           MEM_PUT calls must be used to access memory.
  1296.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  MEMORY )
  1297. MEM_PUT - write to allocated memory area.
  1298.  
  1299.   inputs:     bx = memory mgr handle
  1300.        bp:si = ptr to data
  1301.               di = put location (index from start of block) 0=start of blk
  1302.           cx = length of bp:si data in words
  1303.  
  1304.    output:   no carry = success
  1305.             carry = error code in -ax- (from EMS/XMS driver)
  1306.  
  1307.   note:  This function is called to transfer data to allocated memory.
  1308.          Fatal EMS or XMS transfers are handled internally and
  1309.          result in an error message display.
  1310.             
  1311.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  MEMORY )
  1312. MEM_GET - read from allocated memory area.
  1313.  
  1314.   inputs:      bx = memory mgr handle
  1315.         bp:di = location to store data
  1316.            si = get location (index from start of block)
  1317.            cx = number of words to read
  1318.  
  1319.   output:  no carry = success
  1320.        carry    = error code in -ax- (from EMS/XMS driver)
  1321.  
  1322.   processing: data is read from the start of block for -cx- bytes
  1323.  
  1324.   note:  This function is called to transfer data from allocated memory.
  1325.          Fatal EMS or XMS transfers are handled internally and
  1326.          result in an error message display.
  1327.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  MEMORY )
  1328. MEM_RELEASE  - release allocated memory block.
  1329.  
  1330.   inputs:     bx = memory mgr handle
  1331.   
  1332.   output:     none
  1333.   
  1334.   processing:  1. convert packet into free memory.
  1335.            2. garbage collect on both sides of chain.
  1336.  
  1337.   note:  This function releases blocks of memory which were allocated
  1338.      by mem_allocate.
  1339.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  MEMORY )
  1340. MEM_CLOSE - close memory handler.
  1341.  
  1342.   inputs:     none
  1343.   output:     none
  1344.   
  1345.   note:  This function is called just before the program exits
  1346.      to return all memory back to the SYSTEM.  Normally,
  1347.      this is accomplished in the LIBRARY_TERMINATE function.
  1348.      The error_handler will also call this function if a fatal
  1349.      error causes a direct exit or reboot.
  1350.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  MEMORY )
  1351. DOS_MEM_ALLOCATE - allocate dos memory for direct writes
  1352.  
  1353.   inputs:  dx,ax - number of bytes to allocate
  1354.   
  1355.   output:   no carry  es = segment of memory allocated
  1356.            carry     = failure allocating memory
  1357.  
  1358.   note:  This function is used only if the program wants to read and
  1359.          write memory directly.  Is is faster than MEM_GET and MEM_PUT
  1360.          but is limited to DOS memory only.           
  1361.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  MEMORY )
  1362. DOS_MEM_RELEASE - release memory allocated with DOS_MEM_ALLOCATE
  1363.  
  1364.    inputs:  es = segment of memory to release
  1365.    
  1366.    output:  no carry = success
  1367.            carry = bad segment
  1368.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  MEMORY )
  1369. CHECK_FOR_EMS:      detects EMS driver
  1370.  
  1371.   inputs:  none
  1372.  
  1373.   output:  if CF = 1, no Expanded Memory manager installed
  1374.            if CF = 0, AH = EMM error code
  1375.            if AH = 0, BX = page frame segment address
  1376.            registers changed  AX,BX           
  1377.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  MENU   )
  1378. MENU_SYSTEM - Menu bar display and decode of user selection
  1379.  
  1380.   inputs:  ds:bx - pointer to info structure see COMMON.INC
  1381.           ah - control flags (see below)
  1382.      bar_save        equ    80h    ;save display data under bar
  1383.      bar_restore    equ    40h    ;restore display data under bar before exit
  1384.      bar_display    equ    20h    ;display the menu bar
  1385.      wait_valid_key    equ    10h    ;wait forever till valid key found
  1386.      return_bad_key    equ    08h    ;wait for key and return unknown keys
  1387.      no_mouse_sim    equ    04h    ;do not simulate mouse with arrow keys
  1388.  
  1389.   output:  cl=0   ax=don't care (none key process occurred)
  1390.        cl=1   ax=process ptr
  1391.        cl=2   ax=key (unknown key press)
  1392.        cl=3   ax=click row/column (unknown mouse click)
  1393.        cl=4   ax=key (abort key pressed)
  1394.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  MENU   )
  1395. QMENU_SYSTEM - Quick pulldown menu bar
  1396.  
  1397.    inputs:  ds:bx = pointer to list of names.  (See list format below)
  1398.    
  1399.    output:  ah = main menu index, 0=first item, 1=second, etc. -1=abort key
  1400.             al = sub menu item if present
  1401.  
  1402.    note: The menu list is displayed on the top line of the screen and is
  1403.          built as follows:
  1404.                 db   'main option1',0
  1405.                 db     'sub option1',0
  1406.                 db     'sub option2',0
  1407.                 db    0            ;end of main option1
  1408.                 db   'main option2',0
  1409.                 db    0            ;end of main option2
  1410.                    .
  1411.                    .
  1412.                 db    0            ;end of all options.
  1413.  
  1414.           One zero between strings is a sub menu separation.
  1415.           two zeros between strings is a new main menu item start
  1416.           three zeros is end of all strings.
  1417.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( MESSAGE )
  1418. message - boxed message display
  1419.  
  1420.   inputs:    al = separator           (if flag msg_open)
  1421.              bh = rows in box         (if flag msg_disp)
  1422.              bl = columns in box      (if flag msg_disp)
  1423.              cx = record #            (if flag msg_disp & not msg_rand)
  1424.              dx = box upper left loc  (if flag msg_disp)
  1425.           ds:si = ptr to file name    (if flag msg_open and not msg_ram)
  1426.           ds:si = ptr to msg text     (if flag msg_ram and msg_open)
  1427.              bp = flags, see equates
  1428.              es = file selector       (if not flag msg_open)
  1429.  
  1430.   outputs:   no carry
  1431.                es = file selector  (if no msg_close flag)
  1432.                al = yes/no response (if msg_yesno flag was set)
  1433.              carry
  1434.            ax = error code      xx02 = code error, flag bits in -bp- wrong
  1435.                   xx03 = disk read error
  1436.                     10(decimal) = open error or file not found
  1437.  
  1438.   note:   This function displays a boxed message in various
  1439.           formats.  All messages are found in memory or a file
  1440.           which uses the database format for variable length ascii
  1441.           records.  A specific message is selected by record #
  1442.           using the database library routines.
  1443.  
  1444.           The Hyper text mode uses a special file which is
  1445.           formatted with records compatible with the database
  1446.           variable length record format.  Each record is
  1447.           terminated with a zero.  The record can contain hyper
  1448.           triggers to point to other topics(records).  The hyper
  1449.           triggers consist of the following:
  1450.  
  1451.            byte 0    space  <- the trigger word must start with a space
  1452.            byte 1    1fh    <- the special character signals start of hyper
  1453.            byte 2     n     <- binary number which is record# 1-255
  1454.            byte 3+   ...    <- string which is to be highlighted trigger word
  1455.            byte n    space  <- trigger word is ended with a space
  1456.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( MESSAGE )
  1457. random - generate random number
  1458.  
  1459.    inputs: bx = minimum value of random range
  1460.            bp = maximum value of random range
  1461.            
  1462.    output: ax = random number
  1463.            all registers are restored except for -ax-
  1464. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( MESSAGE )
  1465. GET_RANDOM -  generate random number
  1466.  
  1467.   inputs: (ds:bx)  struc
  1468.                     rs1   dw  (random seed 1)
  1469.                     rs2   dw  (random seed 2)
  1470.                     range dw  mask to truncate number
  1471.                     method db  flag  1 = method 1   2=method 2
  1472.                     
  1473.   output:  ax = random number
  1474.  
  1475.   note:  GET_RANDOM is designed for applications which need to keep several
  1476.          random number sequences going independently.  Normally, the
  1477.          RANDOM function is used instead of GET_RANDOM.
  1478.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( MESSAGE )
  1479. QMESSAGE - Quick message display in box & wait for keypress (msg in file)
  1480.  
  1481.   inputs:     cx = record # to display.
  1482.   
  1483.   output:  carry set if error reading file on disk. File must be in current
  1484.            default directory.
  1485.            
  1486.   note:    The display location, colors, and box size is calculated.
  1487.            The message is obtained from the standard error file, See
  1488.            ERROR_PRIME for selecting file to use.  The message is placed
  1489.            in a box 10 rows long and 40 columns wide.  It waits for any
  1490.            key before preceding.
  1491.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( MESSAGE )
  1492. QWARN - Quick message display in box & wait for keypress (msg in mem)
  1493.  
  1494.   inputs:  ds:si = pointer to message text, zero at end.
  1495.   
  1496.   output:  none
  1497.   
  1498.   note:    The display location, colors, and box size is calculated.
  1499.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1500. IS_ALPHA - check if key returned by KEY_READ is a letter from A-Z or a-z.
  1501.  
  1502.   inputs:    AX = keycode returned by KEY_READ or AH=0, AL=ascii
  1503.   
  1504.   output:    if CF = 0, keycode is a character from A-Z or a-z
  1505.              if CF = 1, keycode is not a character from A-Z or a-z
  1506.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1507. IS_DIGIT - check if key returned by KEY_READ is the ASCII from 0-9
  1508.  
  1509.   inputs:    AX = keycode returned by KEY_READ or AH=0, AL=ascii
  1510.   
  1511.   output:    if CF = 0, keycode is a character from 0-9
  1512.              if CF = 1, keycode is not a character from 0-9
  1513.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1514. IS_LOWER - check if key returned by KEY_READ is lower case
  1515.  
  1516.   inputs:    AX = keycode returned by KEY_READ or AH=0, AL=ascii
  1517.   
  1518.   output:    if CF = 1, keycode is not a character from a-z
  1519.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1520. IS_UPPER - check if key returned by KEY_READ is upper case
  1521.  
  1522.   inputs:    AX = keycode returned by KEY_READ or AH=0, AL=ascii
  1523.  
  1524.   output:   if CF = 1, keycode is not a character from A-Z
  1525.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1526. TO_UPPER - converts ascii character to upper case
  1527.  
  1528.   inputs:    AX = keycode returned by KEY_READ or AH=0, AL=ascii
  1529.   
  1530.   output:    AL = upper case ascii
  1531.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1532. TO_LOWER - converts ascii character lower case
  1533.  
  1534.   inputs:    AX = keycode returned by KEY_READ or AH=0, AL=ascii
  1535.   
  1536.   output:    AL = lower case ascii
  1537.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1538. CAPS_ON - Turn the keyboard CAPS LOCK key on
  1539.  
  1540.   inputs:  none
  1541.   output:  none
  1542.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1543. NUMLOCK_ON - Turn the keyboard NUM LOCK key on
  1544.  
  1545.   inputs:  none
  1546.   output:  none
  1547.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1548. SCROLL_ON - Turn the keyboard SCROLL LOCK key on
  1549.  
  1550.   inputs: none
  1551.   output: none
  1552.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1553. INSERT_OFF - Turn the keyboard INS key off
  1554.  
  1555.   inputs: none
  1556.   output: none
  1557.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1558. CAPS_OFF - Turn the keyboard CAPS LOCK key off
  1559.  
  1560.   inputs: none
  1561.   output: none
  1562.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1563. NUMLOCK_OFF - Turn the keyboard NUM LOCK key off
  1564.  
  1565.   inputs: none
  1566.   output: none
  1567.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1568. SCROLL_OFF - Turn the keyboard SCROLL LOCK key off
  1569.  
  1570.   inputs: none
  1571.   output: none
  1572.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1573. YES_OR_NO - wait for yes or no user response
  1574.  
  1575.    inputs: al - 0=wait for Yes/NO/abort key, and ignore all others
  1576.                 1=wait for Yes/No/abort key, and return others also
  1577.                 
  1578.    outputs: no carry - al = Yes/No ascii character in upper case
  1579.                carry - al = 03 if abort, and others also if requested
  1580.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1581. FLUSH_KEYBOARD - clears the keyboard's 'type-ahead' buffer
  1582.  
  1583.   inputs:  none
  1584.   output:  none
  1585.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1586. KEY_CHECK - check if a key is waiting in the keyboard buffer.
  1587.  
  1588.   inputs:    none
  1589.   
  1590.   output:    AX = 0 if no key waiting
  1591.              AX = 1 if key waiting
  1592.              
  1593.   note:      if key is found in buffer it is left there and the AX register
  1594.              is set to one.
  1595.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1596. KEY_READ - returns next key pressed
  1597.  
  1598.   inputs:  none
  1599.   output:    if AH = 0  AL = ASCII key code
  1600.              if AH = 1  AL = scan code
  1601.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1602. KEY_PUT - put key back into BIOS buffer
  1603.  
  1604.   inputs:  ax = key
  1605.   output:  none
  1606.   
  1607.   Note: If keyboard buffer is full then the key will be ignored.
  1608.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1609. KEY_IF_READY - get next key waiting from keyboard
  1610.  
  1611.   inputs:    none
  1612.   
  1613.   output:    AX = 0 if no key waiting
  1614.              AX = keycode
  1615.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1616. SETUP_MOUSE -  initializes mouse driver if mouse present
  1617.  
  1618.   inputs:    none
  1619.   
  1620.   output:    no carry - mouse is initialized
  1621.                 carry - mouse was not found
  1622.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1623. MOUSE_PARMS - determine mouse position & buttons pressed
  1624.  
  1625.   inputs:    none
  1626.   
  1627.   output:    if ZF = 1, no buttons are pressed
  1628.              if ZF = 0, BX = button code
  1629.               BX bit 0 if set = left button is down
  1630.               BX bit 1 if set = right button is down
  1631.               BX bit 2 if set = center button is down
  1632.              CX = horizontal (x) coordinate
  1633.              DX = vertical (y) coordinate
  1634.              
  1635.   Note that mouse positions are expressed as a pixel location
  1636.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1637. KEY_OR_MOUSE - waits for first keypress or mouse button click
  1638.  
  1639.   inputs:    none
  1640.  
  1641.   output:    AX = keycode, BX = mouse button
  1642.  
  1643.   note:  If a keycode is found it is returned and the mouse status
  1644.          is not checked.
  1645.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1646. MOVE_MOUSE - sets the mouse's position
  1647.  
  1648.   inputs:  dh = text mode row#
  1649.        dl = text mode column#
  1650.        
  1651.   output:  none
  1652.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1653. BOX_THE_MOUSE - limits mouse's range of motion
  1654.  
  1655.   inputs:    dx = box upper left corner (dh=row, dl=column)
  1656.          bx = box size (bh = number of rows,  bl = number of columns)
  1657.  
  1658.   output:   none
  1659.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1660. MOUSE_CURSOR_ON - Enable the mouse cursor display
  1661.  
  1662.   inputs:  none
  1663.   output:  none
  1664.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1665. MOUSE_CURSOR_OFF - Disable the mouse cursor display
  1666.  
  1667.   inputs:  none
  1668.   output:  none
  1669.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1670. GET_STRING - read string from the keyboard.
  1671.  
  1672.  inputs: es:di - point at buffer for string.  Buffer can be preloaded
  1673.                  with default display.  pad rest with zeros or spaces.
  1674.             ah - color for edit line
  1675.             al - color for edit line at exit time
  1676.             ch - length of buffer
  1677.             cl - length of window
  1678.             dh - window row
  1679.             dl - window column (starting)
  1680.             bl - flag 01=numbers only 02h=upper case 04=lower case 08=filename
  1681.               gs_numbers   equ  01h  ;get numbers only
  1682.               gs_upper     equ  02h  ;get upper case characters
  1683.               gs_lower     equ  04h  ;get lower case characters
  1684.               gs_file      equ  08h  ;get filename characters only
  1685.               gs_init      equ  10h  ;initialize (do once per string entry)
  1686.               gs_key_wait  equ  20h  ;input keys till done or unknown key found
  1687.               gs_key_check equ  40h  ;input key only if it is ready
  1688.               gs_close     equ  80h  ;remove cursor and deselect string 
  1689.  
  1690.   output:   cx - size of string entered (-1=unknown key in -ax-)
  1691.             ax - last key code if  cx=-1
  1692.                - zero if gs_key_check and all keys processed ok
  1693.  
  1694.    Note: The buffer length must be equal or greater than the window length
  1695.  
  1696.          get_string is designed to operate in two modes.  The first mode
  1697.          stays in get_string until the string is entered.  This mode requires
  1698.          the flags: ( gs_init,gs_key_wait,gs_close) and all parameters.
  1699.          The second mode allows get_string to poll the keyboard along with
  1700.          other functions.  This mode can be used as follows:
  1701.           1. call with gs_init flag and all parameters.
  1702.           2. call with gs_key_check until string entered or abort key
  1703.           3. call with gs_close to remove the cursor and deselect.
  1704.          Steps 2&3 above only require the flag information in -bl- along
  1705.          with the get_string call.
  1706.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1707. KEY_DECODE - scan for special keys, determine key type and process flags.
  1708.  
  1709.   inputs: ah=key scan code
  1710.           al=key ascii code
  1711.        ds:si=pointer to decode table
  1712.        
  1713.   output: if cx = 0 then,
  1714.              al = key ascii code
  1715.              ah = extended/normal key flag
  1716.              bx = processing offset (set to normal key if not in table and ah=0)
  1717.           if cx=-1 then ax = illegal key
  1718.  
  1719.   note:   All keys not in table which have extended flag set are ignored.
  1720.           Normal keys are processed using control flag supplied by user.
  1721.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1722. QGET_STRING - Quick call to get string & return when done
  1723.  
  1724.   inputs: cl = max string length (buffer length)
  1725.           dx = display location (dh=row,dl=column)
  1726.           es:di = pointer to buffer for data storage
  1727.           
  1728.   output: cx = size of string entered, if -1 then illegal key (ax has key)
  1729.           ax = if cx = -1 then cx=illegal key code
  1730.                
  1731.   notes: This routine calls GET_STRING with some standard settings.
  1732.          For full control use GET_STRING instead.         
  1733.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1734. WINDOW_EDIT - edit text within window
  1735.  
  1736.    inputs:  bx = window frame size (bh-rows bl=columns)
  1737.             dx = window position (dh=row dl=column)
  1738.          ds:si = data for window
  1739.             cx = size of data buffer (must be larger than window by 20%)
  1740.             
  1741.    outputs:    ah = -1 (abort key pressed)
  1742.                 al = last key press if normal exit
  1743.                 carry set = changes make to buffer
  1744.                
  1745.    processing:  1. display window data with cursor, then respond
  1746.                    to edit keys:  ctrl-c  = abort
  1747.                                   Enter   = break this line
  1748.                                   ESC     = exit edit mode
  1749.                                   right   = cursor right
  1750.                                   left    = cursor left
  1751.                                   up      = cursor up
  1752.                                   down    = cursor down
  1753.                                   home    = cursor to left edge
  1754.                                   end     = cursor to right edge
  1755.                                   del     = delete char. under cursor
  1756.                                   back    = delete & move back
  1757.                                   F1      = hyper word select
  1758.  
  1759.   note:  Normal ascii characters are entered into the buffer and
  1760.          the buffer updated.  The state of INS key determines
  1761.          if characters are inserted or overtype occurs.  Illegal
  1762.          key cause a beep and are ignored.
  1763.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(MOUSE/KEY)
  1764. WINDOW_CSTRING - display text with hyper formating
  1765.  
  1766.   inputs:    DS:[SI] pointing to the string
  1767.              ds:[di] points to cursor posn in buffer
  1768.           dx = starting row(dh)  starting column(dl)
  1769.           bx = box total rows(bh)  box total columns(bl)
  1770.              AH = color attribute (must be msg_text_color)
  1771.              
  1772.   outputs:   table line_table is prepared.
  1773.              cursor information is updated.
  1774.  
  1775.   note:     WINDOW_CSTRING was written to be used by WINDOW_EDIT to
  1776.             display in a window and handle hyper words.  It does word
  1777.             wrap and handles cr/lf characters.  The window text is
  1778.             assumed to be terminated with a null character.
  1779.  
  1780.             Unused portions of the window are cleared.
  1781.             
  1782.             HYPER triggers are imbedded into the text as two bytes which are
  1783.             encoded as follows: 
  1784.                                  first byte   1fh         <-character
  1785.                                  second byte  (record #)  <-binary value
  1786.  
  1787.             HYPER words must begin and end with a space with the HYPER
  1788.             trigger after the first space.  The EDREC utility program
  1789.             is an easy way to create HYPER entires.
  1790.             
  1791.             The text must be in a buffer larger than the window to allow
  1792.             for inserts.  It is possible for the text to overflow the
  1793.             buffer slightly and not show on the display.
  1794.             
  1795.           The line_info table is built from text scan and is
  1796.           available as output to callers.  Its intended use is
  1797.           to speed processing of hyper trigger words.  The format
  1798.           of the line_table is:
  1799.  
  1800.           line_struc    struc
  1801.            line_start    dw    ?    ;ptr to first char. of line
  1802.            line_end    dw    ?    ;ptr to last char, 0=end of data 0d=cr/lf at end
  1803.                            ;                  n=wrap occurred
  1804.            chars        db    ?    ;number of chars (minus hyper triggers, cr/lf)
  1805.            line_no    db    ?    ;line number in range 0-24
  1806.           line_struc    ends
  1807.  
  1808.           line_tbl_size    equ    25
  1809.  
  1810.           line_table    label    byte
  1811.               line_struc<?,?,?,0>
  1812.         line_struc<?,?,?,01>
  1813.         line_struc<?,?,?,02>
  1814.         line_struc<?,?,?,03>
  1815.         line_struc<?,?,?,04>
  1816.         line_struc<?,?,?,05>
  1817.         line_struc<?,?,?,06>
  1818.         line_struc<?,?,?,07>
  1819.         line_struc<?,?,?,08>
  1820.         line_struc<?,?,?,09>
  1821.         line_struc<?,?,?,10>
  1822.         line_struc<?,?,?,11>
  1823.         line_struc<?,?,?,12>
  1824.         line_struc<?,?,?,13>
  1825.         line_struc<?,?,?,14>
  1826.         line_struc<?,?,?,15>
  1827.         line_struc<?,?,?,16>
  1828.         line_struc<?,?,?,17>
  1829.         line_struc<?,?,?,18>
  1830.         line_struc<?,?,?,19>
  1831.         line_struc<?,?,?,20>
  1832.         line_struc<?,?,?,21>
  1833.         line_struc<?,?,?,22>
  1834.         line_struc<?,?,?,23>
  1835.         line_struc<?,?,?,24>
  1836.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  PARSE  )
  1837. PARSE_FIRST - parse first argument from command line
  1838.  
  1839.   inputs: es:di = location to store parsed string
  1840.   
  1841.   output: es:di = (unchanged) parsed string ptr
  1842.           cx = length of parsed string (0=no more parameters available)
  1843.     bh,dx,ax   are set as specified by the flag value in -bh-
  1844.           bh = 0 - end of parameters
  1845.                   1 - single alpha parameter was found of form "\x". The
  1846.                       "x" character was placed in register -bl-
  1847. 2 - single numeric parameter was found of form "\n". The
  1848.                       "n" binary value was placed in register -bl-
  1849.                  3 - compound alpha parameter of form "\x:yyyy" was found.
  1850.                       register -bl- has "x" character.
  1851.                   4 - compound numeric parameter of form "\x:nnnn" was found.
  1852.                       register -bl- has "x" character, dx,ax has value of nnnn
  1853.                   5 - found alpha string of form "\xxxxx"
  1854.                   6 - found value of form "\nnnn".  The decimal value of
  1855.                nnnn was placed in registers dx,ax
  1856.                   7 - found alpha string of form "xxxx"
  1857.                   8 - found numeric string of form "nnnn".  The decimal
  1858.                value of nnnn was placed in registers dx,ax
  1859.  
  1860.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  PARSE  )
  1861. PARSE_NEXT - parse next command line parameter
  1862.  
  1863.   inputs:  (see PARSE_FIRST)
  1864.   
  1865.   outputs: (see PARSE_FIRST)
  1866.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1867. STRLEN1 - finds length of a ASCII string at DS:SI
  1868.  
  1869.   inputs:    DS:[SI] = address of the string
  1870.   
  1871.   output:    CX = length of string excluding the terminating NUL
  1872.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1873. STRLEN2 - finds length of a ASCII string at DS:DI
  1874.  
  1875.   inputs:    DS:[DI] = address of the string
  1876.   
  1877.   output:    CX = length of string excluding the terminating NUL
  1878.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1879. STRLEN3 - finds length of a ASCII string at DS:BX
  1880.  
  1881.   inputs:    DS:[BX] = address of the string
  1882.   
  1883.   output:    CX = length of string excluding the terminating NUL
  1884.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1885. LAST_CHAR - find the last byte in a string matching register AL
  1886.  
  1887.   inputs:    DS:[BX] pointing to the first character of the string
  1888.              AL = byte to find
  1889.              
  1890.   output:    if CF = 1, no match
  1891.              if CF = 0, AX = offset from DS:[BX] of the last matching byte
  1892.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1893. LAST_CHARC - find the last byte in n bytes matching AL
  1894.  
  1895.   inputs:    DS:[BX] pointing to the first character of the string
  1896.              AL = byte to find
  1897.              CX = number of bytes to search
  1898.              
  1899.   output:    if CF = 1, no match
  1900.              if CF = 0, AX = offset from DS:[BX] of the last matching byte
  1901.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1902. FIRST_CHAR -  search an ASCIIZ string for a specified character
  1903.  
  1904.   inputs:    DS:[SI] = pointer to ASCIIZ string
  1905.              AL = character to find
  1906.              
  1907.    output:    if no carry - DI points at match point
  1908.               if carry - char. was not found
  1909.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1910. FIRST_CHARC - search n bytes of an ASCII string for a specified character
  1911.  
  1912.   inputs:    DS:[SI] = pointer to ASCIIZ string
  1913.              AL = character to find
  1914.              CX = number of bytes to search
  1915.              
  1916.   output:    if no carry - DI points at match point
  1917.              if carry - char. was not found
  1918.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1919. BUFFER_SEARCH - search string1 for the first occurrence of string2
  1920.  
  1921.   inputs:    ES:[DI] pointing to string1
  1922.              DS:[SI] pointing to string2
  1923.              
  1924.   output:    if no carry - DI = offset of target in source string.
  1925.              if carry -  no match
  1926.  
  1927.   note:  case is ignored.  Strings must end with null character (zero).
  1928.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1929. BUFFER_SEACHC - search a buffer for the first occurrence of a string
  1930.                       
  1931.   inputs:    ES:[DI] pointing to buffer
  1932.              DS:[SI] pointing to match-string.
  1933.                  cx = length of buffer
  1934.  
  1935.   output:    if no carry - DI = offset of target in source string.
  1936.              if carry - no match
  1937.  
  1938.   note:  case is ignored.  Match string in DS:SI must end with zero.
  1939.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1940. STR_SRCHC - finds the first match with a target string in a source string
  1941.  
  1942.   inputs:    ES:[DI] pointing to source string
  1943.              DS:[SI] pointing to target string.
  1944.              
  1945.   output:    if CF = 0, BX = offset of target in source string.
  1946.              if CF = 1, no match
  1947.              AX, CF; all other flags and registers are saved
  1948.  
  1949.   note:      case of strings must also match.
  1950.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1951. LAST_STR -  finds the last match with a target string in a source string
  1952.  
  1953.   inputs:    ES:[DI] pointing to source string
  1954.              DS:[SI] pointing to target string.
  1955.              
  1956.   output:    if no carry - BX = offset of target in source string.
  1957.              if carry - no match
  1958.              
  1959.   note:      case of strings must also match.
  1960.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1961. LEGAL_CHAR_CHECK - scan target string for legal characters
  1962.  
  1963.   inputs:  ds:si = target string ptr
  1964.               bx = length of string
  1965.            es:di = legal character list
  1966.               dx = length of legal char list
  1967.              
  1968.   output: carry set if invalid character found. ds:si points at character
  1969.  
  1970.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1971. ILLEGAL_CHAR_CHECK - scan string for illegal characters
  1972.  
  1973.   inputs: ds:si = target string
  1974.              bx = length of target string
  1975.           es:di = list of illegal/check characters
  1976.              dx = length of check list
  1977.             
  1978.   output: carry set if illegal/check character found.  DS:SI point at match.
  1979.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1980. STR_UPPER - changes string to upper case
  1981.  
  1982.   inputs:    DS:[SI] pointing to string
  1983.   
  1984.   output:    nothing
  1985.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1986. STR_UPPERC:  changes n-length string to upper case
  1987.  
  1988.   inputs:    DS:[SI] pointing to string
  1989.              CX = number of bytes in string
  1990.              
  1991.   output:    nothing
  1992.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1993. STR_LOWER - changes bytes of a string to lower case
  1994.  
  1995.   inputs:    DS:[SI] = address of an ASCIIZ string
  1996.   
  1997.   output:    nothing
  1998.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  1999. STR_LOWERC -  changes n bytes of a string to lower case
  2000.  
  2001.   inputs:    DS:[SI] = address of an ASCIIZ string
  2002.              CX = number of bytes
  2003.              
  2004.   output:    nothing
  2005.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2006. STR_CENTER - centers string1 in a string2
  2007.  
  2008.   inputs:    ES:[DI] = address of string2
  2009.              DS:[SI] = address of string1
  2010.              
  2011.   output:    CF = 0 if no error
  2012.              CF = 1 if string was truncated to fit in the field
  2013.  
  2014.   Note:  The length of string2 is determined, then string2 is cleared
  2015.          to all spaces.  String1 is then centered within string2.
  2016.          Both strings must be null terminated.
  2017.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2018. STR_LEFT - left-justifies string1 in string2
  2019.  
  2020.   inputs:    ES:[DI] = address of string2
  2021.              DS:[SI] = address of string1
  2022.              
  2023.   output:    CF = 0 if no error
  2024.              CF = 1 if string was truncated to fit in the field
  2025.  
  2026.   note:  string2 is first filled with spaces, then string1 is moved
  2027.          into string2.  Both strings must be null terminated.         
  2028.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2029. STR_RIGHT - right-justifies a string1 in string2
  2030.  
  2031.   inputs:    ES:[DI] = address of string2
  2032.              DS:[SI] = address of string1
  2033.              
  2034.   output:    CF = 0 if no error
  2035.              CF = 1 if string was truncated to fit in the field
  2036.  
  2037.   note:  string2 is first filled with spaces, then string1 is moved
  2038.          into string2.  Both strings must be null terminated.
  2039.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2040. STR_CLEANL - remove leading blanks from an ASCIIZ string
  2041.  
  2042.   inputs:    DS:[SI] pointing to string
  2043.   
  2044.   output:    CX = string length
  2045.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2046. STR_CLEANR - removes trailing blanks from string
  2047.  
  2048.   inputs:    DS:[SI] pointing to string
  2049.   
  2050.   output:    CX = string length
  2051.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2052. STR_REMOVE - remove all occurrences of a character from string.
  2053.  
  2054.   inputs:    DS:[SI] = string address
  2055.              AL = character to remove from the string
  2056.              
  2057.   output:    CX = string length
  2058.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2059. STR_CHAR_DEL - deletes a character from a string
  2060.  
  2061.   inputs:    DS:[SI] points to string
  2062.              AX = offset from DS:[BX] to character to delete
  2063.              
  2064.   output:    CX = string length
  2065.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2066. STR_CHAR_DELC - deletes a character from a string of n-length
  2067.  
  2068.   inputs:    DS:[SI] pointing to an ASCIIZ string
  2069.              CX = current string length
  2070.              AX = offset from DS:[BX] to character to delete
  2071.              
  2072.   output:    CX = string length
  2073.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2074. STR_REVERSE - reverses all characters in a string
  2075.  
  2076.   inputs:    DS:[SI] pointing to the first character of the string
  2077.              
  2078.   output:    CX = string length
  2079.  
  2080.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2081. STR_REVERSEC - reverses n characters in a string
  2082.  
  2083.   inputs:    DS:[SI] pointing to the first character of the string
  2084.              CX = number of bytes in string to reverse
  2085.              
  2086.   output:    CX = string length
  2087.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2088. STR_SWAP - swaps portions of two strings
  2089.  
  2090.   inputs:    DS:[SI] points to string1
  2091.              ES:[DI] points to string2
  2092.              CX = number of bytes to swap
  2093.              
  2094.   output:    nothing
  2095.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2096. STR_SET - sets all bytes of string to a specified character
  2097.  
  2098.   inputs:    DS:[SI] pointing to a string
  2099.              AL = character
  2100.              
  2101.   output:    none
  2102.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2103. STR_SETC - sets n bytes of string to a specified character
  2104.  
  2105.   inputs:    DS:[SI] points to string
  2106.              AL = character
  2107.              CX = number of bytes to set
  2108.              
  2109.   output:    none
  2110.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2111. STR_JOIN -  appends string2 at end of string1
  2112.  
  2113.   inputs:    es:[dI] = address of first string
  2114.                  bx  = length of string 1
  2115.               ds:si  = address of second string
  2116.                  dx  = length of string 2     
  2117.                  
  2118.   output:  es:di = new string ptr (unchanged from input DS:SI)
  2119.               cx = length of joined string at es:di
  2120. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2121. STR_INSERT - inserts string1 in string2 at specified offset.
  2122.  
  2123.  inputs:    DS:[SI] pointing to string1
  2124.             ES:[DI] pointing to string2
  2125.             AX = offset in string2 to insert string1
  2126.             
  2127.  output:  none
  2128.  
  2129.  note:  The buffer containing string2 must be large enough for
  2130.         expansion to the size of string1 plus string2.
  2131.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( STRING  )
  2132. STR_COPY - copy a string to existing buffer
  2133.  
  2134.   inputs:    DS:[SI] pointing to string
  2135.              ES:[DI] pointing to destination buffer
  2136.              
  2137.   output:    CX = string length
  2138.  
  2139.   note:      The string's terminating NUL byte is also copied.
  2140.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  STRING )
  2141. STR_COPYC - copy CX bytes to an existing buffer
  2142.  
  2143.   inputs:    DS:[SI] pointing to ASCII string
  2144.              ES:[DI] pointing to destination buffer
  2145.              CX = number of bytes to copy
  2146.  
  2147.   output:    nothing
  2148.  
  2149.   note:      The string's terminating NUL byte is NOT copied.
  2150.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2151. LIBRARY_SETUP - setup library for use
  2152.  
  2153.    inputs:  ax = psp segment
  2154.             bx = number of floating variables needed
  2155.             
  2156.    output:  es:si = pointer to library info structure
  2157.          carry = error, library unusable
  2158.  
  2159.        info    struc
  2160.         cpu_type    db    ?    ;0=88 1=186 2=286 3=386 4=486
  2161.         math_chip    db    ?    ;0=none 1=8087 2=287 3=387 4=487
  2162.         mouse_present    db    ?    ;0=no n=yes
  2163.         crt_type    db    ?    ;
  2164.         crt_mode    db    ?
  2165.         mono_flag    db    ?
  2166.         ansi_present    db    ?    ;0=no 1=yes
  2167.         users_color    db    ?
  2168.         crt_seg    dw    ?    ;segment of crt buffer
  2169.         crt_rows    db    ?    ;
  2170.         crt_columns    db    ?    ;
  2171.         key_type    db    ?    ;0=old style 1=enhanced
  2172.         psp_seg    dw    ?
  2173.        info    ends
  2174.          
  2175.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2176. LIBRARY_TERMINATE - close out library for program exit
  2177.  
  2178.    inputs:  ax = 0 clear screen at exit
  2179.             ax = 1 do not clear screen
  2180.             
  2181.    output:  none
  2182.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2183. FIND_CPU_TYPE - detects cpu type
  2184.  
  2185.   inputs:  none
  2186.   
  2187.   output:    AX = 0 if 8086/8088
  2188.              AX = 1 if 80186/80188
  2189.              AX = 2 if 80286
  2190.              AX = 3 if 386 (SX or DX)
  2191.              AX = 4 if 486 (SX or DX)
  2192.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2193. MATH_HARDWARE - determines if 80x87 math coprocessor is installed
  2194.  
  2195.   inputs:    none
  2196.   
  2197.   output:    AX = code for 80x87 model
  2198.              0 = not installed
  2199.              1 = 8087
  2200.              2 = 287
  2201.              3 = 387 (DX or SX)
  2202.              4 = 487 (486DX or 487SX)
  2203.              If the coprocessor is present, it is initialized by MATH_HARDWARE.
  2204.              
  2205.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2206. keyboard_setup - determine type of keyboard attached
  2207.  
  2208.   inputs: none
  2209.   
  2210.   output: al = 0(old style bios)  1(enhanced bios)
  2211.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2212. FIND_MOUSE - determines if a mouse is installed
  2213.  
  2214.   inputs:    none
  2215.   
  2216.   output:    AX = number of mouse buttons
  2217.              AX = 0 if no mouse or mouse driver installed
  2218.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2219. CHECK_ANSI - check if ANSI active
  2220.  
  2221.   inputs:    none
  2222.   
  2223.   output:    CF = 1 if no ANSI driver active
  2224.              CF = 0 if ANSI active
  2225.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2226. DISPLAY_INFO - determine display information
  2227.  
  2228.   inputs:    none
  2229.              
  2230.   output:    AL = screen rows
  2231.              CH = screen columns
  2232.              BX:[SI] = video buffer address
  2233.              register DX is modified
  2234.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2235. DETECTVID -  determine display type
  2236.  
  2237.    inputs: none
  2238.    
  2239.    outputs:  ax = 0  no display
  2240.                   1  monochrome
  2241.                   2  hercules 
  2242.                   3  cga digital (mono)
  2243.                   4  cga analog  (mono)
  2244.                   5  cga analog (color)
  2245.                   6  ega mono
  2246.                   7  ega color 64k
  2247.                   8  ega color 64k+
  2248.                   9  cga compatable
  2249.                  10  vga mono
  2250.                  11  vga color 
  2251.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2252. FIND_DISPLAY_SEGMENT  -  scan for current display buffer segment
  2253.  
  2254.    inputs:   display mode 3 or 7 must be set and display page must = 0
  2255.    
  2256.    output:   display_segment is set
  2257.  
  2258.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2259. SPAWN_DOS - execute a second copy DOS
  2260.  
  2261.   inputs:    DS:[SI] points to command tail
  2262.              See DOS function 4bh for more information on command tail.
  2263.              
  2264.              if DS:[SI] points to a nul byte, control is transferred
  2265.              to the second copy of COMMAND.COM and you get a DOS prompt.
  2266.              control is passed back to the calling program when EXIT is
  2267.              entered at the DOS prompt.
  2268.  
  2269.              if DS:[SI] points to a program name string, the program
  2270.              will be executed, and control will pass back to the calling
  2271.              program at the termination of the second program.
  2272.              
  2273.   output:    nothing
  2274.  
  2275.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2276. COUNT_FLOP_DRIVES - count the number of floppy disk drives installed
  2277.  
  2278.   inputs:    no parameters
  2279.   
  2280.   output:    AX = number of floppy drives
  2281.   
  2282.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2283. GET_DRV_TYPE - determine drive type
  2284.  
  2285.   inputs:    DL = drive number (0 = drive A:)
  2286.   
  2287.   output:    AX = floppy drive type
  2288.               0 = invalid drive number
  2289.               1 = 360k
  2290.               2 = 1.2M
  2291.               3 = 720k
  2292.               4 = 1.44M
  2293.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2294. BREAK_KEY_INTERCEPT - grab keyboard abort keys
  2295.  
  2296.   inputs:  none
  2297.   output:  none
  2298.  
  2299.   note:      BREAK_KEY_INTERCEPT traps Ctrl+Break, Ctrl+C and
  2300.              Ctrl-Alt-Del key sequences.  When one of these
  2301.              key combinations is pressed, the information is passed
  2302.              to KEY_READ, KEY_IF_READY, KEY_OR_MOUSE.
  2303.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2304. BREAK_KEY_RESTORE - release keyboard abort keys
  2305.  
  2306.   inputs:    no parameters
  2307.   output:    nothing
  2308.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -( SYSTEM  )
  2309. BREAK_CHECK -  check if break key pressed
  2310.  
  2311.   inputs:  none
  2312.   output:  flags set for je or jz if not set
  2313.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  TIME  )
  2314. DAYS_TO_DATE - build date for the number of days since Jan 1, 1980.
  2315.  
  2316.   input:  AX =     days elapsed since January 1, 1980 ("numdays")
  2317.  
  2318.   output: DX        year (1980-2099)
  2319.       AH        month (1-12)
  2320.       AL        day (1-31)
  2321.  
  2322.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  TIME  )
  2323. MONTH_TO_ASCII - get ASCII string for specified month
  2324.  
  2325.   inputs:    CX = month (1 - 12, January = 1)
  2326.   
  2327.   output:    ES:[DI] = pointer to month name string
  2328.              CX = length of month string
  2329.  
  2330.   Note: the day name string is not zero-terminated
  2331.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  TIME  )
  2332. DAY_TO_ASCII - get string for specified day of the week
  2333.  
  2334.   inputs:    CX = day of week (1 - 7, Sunday = 1)
  2335.   
  2336.   output:    ES:[DI] = pointer to day name string
  2337.              CX = length of new string
  2338.              
  2339.   Note: the day name string is not zero-terminated
  2340.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  TIME  )
  2341. GET_TIME - Returns the current SYSTEM time.
  2342.  
  2343.   input:  None
  2344.  
  2345.   output: DH        hours (0-23)
  2346.       DL        minutes (0-59)
  2347.       AH        seconds (0-59)
  2348.       AL        hundredths of seconds (0-99)
  2349.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  TIME  )
  2350. ASC_TIME - Creates a time string of the form HH:MM Xm.
  2351.  
  2352.   input: DS:SI        destination string ("string")
  2353.     Time in dword format ("time"):
  2354.       DH        hours (0-23)
  2355.       DL        minutes (0-59)
  2356.       
  2357.   output: SI points past last store point      
  2358.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  TIME  )
  2359. GET_DATE - Returns the current SYSTEM date and day of the week.
  2360.  
  2361.   input:  None
  2362.   
  2363.   output: Current SYSTEM date, in dword format:
  2364.       DX        year (1980-2099)
  2365.       AH        month (1-12)
  2366.       AL        day (1-31)
  2367.           CL        day-of-the-week (number of days since Sunday)
  2368.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  TIME  )
  2369. GET_DAY - Returns the day of the week for a given date.
  2370.  
  2371.   input: Date for which day of week should be determined, in dword
  2372.       DX        year (1980-2099)
  2373.       AH        month (1-12)
  2374.       AL        day (1-31)
  2375.  
  2376.   output: CL        day of the week (0-6)
  2377.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  TIME  )
  2378. ASC_DATE - Creates a date string of the form MM/DD/YY.
  2379.  
  2380.   input:  DX        year (1980-2099)
  2381.       AH        month (1-12)
  2382.       AL        day (1-31)
  2383.     DS:SI        destination string ("string")
  2384.  
  2385.   output: si points past last character stored.      
  2386.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(  TIME  )
  2387. DATE_TO_DAYS - get number of days between Jan 1, 1980 and a date.
  2388.  
  2389.   input:  DX        year (1980-2099)
  2390.       AH        month (1-12)
  2391.       AL        day (1-31)
  2392.  
  2393.   output: AX        days elapsed since January 1, 1980
  2394.